Calibrate against several LC setups at once (v4.3.0) - #117

What

Calibration ranks all 6,543 heads of the multitask model and keeps exactly one (_best_correlating_head), so a gradient that sits between trained setups is described by the closest single setup and the other 6,542 columns are thrown away.

MultiHeadRidgeCalibration keeps that same ranking, calibrates the 80 best heads individually with SplineTransformerCalibration, and fits a ridge regression from those calibrated estimates onto the observed retention times. Each head contributes an estimate already in the reference's unit; the ridge decides how much to trust each one.

This is now the default for multitask models (updated after review): calibrate and predict_and_calibrate use MultiHeadRidgeCalibration whenever the model predicts for more than one LC setup, and keep SplineTransformerCalibration for single-task models. The previous behaviour is one argument away:

from deeplc import predict_and_calibrate
from deeplc.calibration import SplineTransformerCalibration

rt = predict_and_calibrate(psms, psm_list_reference=reference,
                           calibration=SplineTransformerCalibration())

Calibration.uses_all_heads (new, False everywhere else) is what tells calibrate/predict_and_calibrate to hand over the whole (n, n_heads) matrix instead of one column.

Result on the eight held-out PRIDE setups (Figure 1b corpus)

Reference and test peptides are disjoint; relative MAE is MAE / observed gradient span. Measured through the public API, not a notebook reimplementation.

8 of 8 improved, median 0.01248 → 0.01090 (13 %). PXD082486 pools several fractions into one run, so its retention times are not a single gradient and nothing helps there; PXD080314 is the wheat-gluten out-of-domain case.

Cost

Not slower than the current path: median calibration fit 2.3 s → 1.0 s, because _best_correlating_head loops in Python over 6,543 columns with np.corrcoef per column while the new ranking is vectorised. (That suggests a separate small win: vectorising the existing helper.) Prediction is unchanged — the full matrix is computed either way.

How 80 was chosen

A sweep over k = 1, 2, 3, 5, 10, 20, 40, 80, 160, 320, 640, 1280, 2000 on the same corpus: median relative MAE 0.01248 (k=1) → 0.01137 (10) → 0.01090 (80, flat to 320) → 0.01125 (2000). Also compared, and rejected:

• unweighted average instead of ridge: best 0.01198 at k=5, and worse than one head beyond k≈40, since equal weights give a head correlating 0.7 the same say as one at 0.999;
• LASSO: matches the ridge (0.01093) while keeping 8-15 non-zero heads, so the same information, no advantage;
• ranking after calibration (rank by MAE once each head is calibrated): reaches 0.01078, marginally better, but it costs ~2,000 extra spline fits per calibration and the ranking criterion is in-sample. Not worth the cost, so the production Pearson ranking is kept.

The class also never fits more weights than half the reference supports, which matters for the 230-peptidoform case.

Verification

• pytest tests: 141 passed, including 12 new tests in tests/test_multihead_calibration.py (beats a single head when the target mixes two setups, records the best head, guards on unfitted use and mismatched head counts, 1-D input, weight cap, empty input, and the two core integration paths).
• ruff check / ruff format --check: clean.
• Version 4.3.0, CHANGELOG and docs/source/models.rst updated.

🤖 Generated with Claude Code